🛡️ Sentinel: [MEDIUM] Fix TOCTOU vulnerability in index.html generation via Atomic Move - #393

🌐 Web query:

According to the Java Files.move documentation, when StandardCopyOption.ATOMIC_MOVE is specified with REPLACE_EXISTING, are other options ignored, and what behavior is permitted if the target already exists?

💡 Result:

According to the official Java documentation for the Files.move method, when the StandardCopyOption.ATOMIC_MOVE option is specified, all other copy options (including REPLACE_EXISTING) are ignored [1][2]. Regarding the behavior when the target file already exists and ATOMIC_MOVE is used, the documentation states that it is implementation-specific whether the existing file is replaced or if the method fails by throwing an IOException [1][2][3]. Because the move must be performed as an atomic file system operation, the platform's native capabilities determine the outcome if a conflict exists at the target path [1][4]. If the underlying file system cannot perform the move atomically, the method will throw an AtomicMoveNotSupportedException [1][2].

Citations:

• 1: https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/nio/file/Files.html
• 2: https://docs.oracle.com/en/java/javase/23/docs/api/java.base/java/nio/file/Files.html
• 3: https://docs.oracle.com/javase/8/docs/api/java/nio/file/Files.html
• 4: https://dev.java/learn/java-io/file-system/move-copy-delete/

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== locate files =="
git ls-files | rg '(^|/)(main\.kt|MainTest\.kt|sentinel\.md)$' || true

echo "== main.kt relevant section =="
if [ -f src/main/kotlin/html4tree/main.kt ]; then
  nl -ba src/main/kotlin/html4tree/main.kt | sed -n '310,365p'
fi

echo "== MainTest.kt relevant section =="
if [ -f src/test/kotlin/html4tree/MainTest.kt ]; then
  nl -ba src/test/kotlin/html4tree/MainTest.kt | sed -n '360,400p'
fi

echo "== sentinel relevant section =="
if [ -f .jules/sentinel.md ]; then
  nl -ba .jules/sentinel.md | sed -n '80,100p'
fi

echo "== search moveFile/write_index_file usages =="
rg -n "moveFile\(|write_index_file\(|StandardCopyOption\.ATOMIC_MOVE|ATOMIC_MOVE|FileAlreadyExistsException|AtomicMoveNotSupportedException" src/main/kotlin src/test/kotlin .jules || true

echo "== parse main.kt function outline =="
ast-grep outline src/main/kotlin/html4tree/main.kt --view compact || true

Repository: ContextualWisdomLab/html4tree

Length of output: 348

🌐 Web query:

Java NIO Files.move StandardCopyOption ATOMIC_MOVE ignore REPLACE_EXISTING target already exists exception implementation specific

💡 Result:

When using the ATOMIC_MOVE option in Java's Files.move method, the behavior regarding an existing target file is explicitly implementation-specific [1][2]. According to the official Java documentation, if the ATOMIC_MOVE option is specified, all other copy options (such as REPLACE_EXISTING) are ignored [1][2]. If the target file already exists during an ATOMIC_MOVE operation, the implementation determines whether it is replaced or if the method fails by throwing an IOException [1][2]. Key points regarding this behavior: 1. Ignored Options: When ATOMIC_MOVE is used, the REPLACE_EXISTING option is explicitly ignored [1][2]. You cannot guarantee replacement by simply combining these two options. 2. Implementation Specificity: Because the outcome depends on the underlying file system and the Java implementation, you cannot rely on a consistent cross-platform behavior when a target exists during an atomic move [1][2]. 3. Atomic Constraint: If the file system cannot perform the move as an atomic operation (for example, if the source and target are on different file stores), the method will throw an AtomicMoveNotSupportedException [1][2]. 4. Non-Atomic Behavior: If you omit ATOMIC_MOVE and use only REPLACE_EXISTING, the operation is generally not atomic [1][2]. In non-atomic moves, if another process creates a file at the target path after the implementation checks for existence but before the move is finalized, a FileAlreadyExistsException may still be thrown despite the presence of REPLACE_EXISTING [1][3][4]. If you require an atomic move that fails if the target exists, or one that consistently replaces it, the Java NIO API does not provide a platform-independent way to enforce this behavior beyond the current implementation-defined limits [1][5]. Developers are advised to handle the potential IOException or AtomicMoveNotSupportedException explicitly within their application logic [1][2].

Citations:

• 1: https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/nio/file/Files.html
• 2: https://docs.oracle.com/javase/8/docs/api/java/nio/file/Files.html
• 3: openjdk/jdk@19287ee
• 4: https://bugs.openjdk.org/browse/JDK-8323194
• 5: https://stackoverflow.com/questions/74335847/perform-atomic-move-operation-but-throw-if-target-exist

• src/main/kotlin/html4tree/main.kt#L342-L344 (this comment)
• src/test/kotlin/html4tree/MainTest.kt#L382-L391
• .jules/sentinel.md#L92-L95